home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / cmds / gdb-4.5 / ds3100.md / bfd / doc / bfd.info-1 < prev    next >
Encoding:
Text File  |  1992-07-01  |  49.0 KB  |  1,541 lines

  1. Info file bfd.info, produced by Makeinfo, -*- Text -*- from input
  2. file ./bfd.texinfo.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Bfd: (bfd).            The Binary File Descriptor library.
  6. END-INFO-DIR-ENTRY
  7.  
  8. This file documents the BFD library.
  9.  
  10. Copyright (C) 1991 Free Software Foundation, Inc.
  11.  
  12. Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16. Permission is granted to copy and distribute modified versions of this
  17. manual under the conditions for verbatim copying, subject to the
  18. terms of the GNU General Public License, which includes the provision
  19. that the entire resulting derived work is distributed under the terms
  20. of a permission notice identical to this one.
  21.  
  22. Permission is granted to copy and distribute translations of this
  23. manual into another language, under the above conditions for modified
  24. versions.
  25.  
  26.  
  27. 
  28. File: bfd.info,  Node: Top,  Next: Overview,  Prev: (dir),  Up: (dir)
  29.  
  30. This file documents the binary file descriptor library libbfd.
  31.  
  32. * Menu:
  33.  
  34. * Overview::            Overview of BFD
  35. * BFD front end::        BFD front end
  36. * BFD back end::        BFD back end
  37. * Index::            Index
  38.  
  39.  
  40. 
  41. File: bfd.info,  Node: Overview,  Next: BFD front end,  Prev: Top,  Up: Top
  42.  
  43. Introduction
  44. ************
  45.  
  46. Simply put, BFD is a package which allows applications to use the same
  47. routines to operate on object files whatever the object file format. 
  48. A different object file format can be supported simply by creating a
  49. new BFD back end and adding it to the library.
  50.  
  51. BFD is split into two parts; the front end and the many back ends.
  52.  
  53. * memory, and various canonical data structures. The front end also
  54. decides which back end to use, and when to call back end routines.
  55.  
  56. * end provides a set of calls which the BFD front end can use to
  57. maintain its canonical form. The back ends also may keep around
  58. information for their own use, for greater efficiency.
  59.  
  60. * Menu:
  61.  
  62. * History::            History
  63. * How It Works::        How It Works
  64. * What BFD Version 1 Can Do::    What BFD Version 1 Can Do
  65.  
  66.  
  67. 
  68. File: bfd.info,  Node: History,  Next: How It Works,  Prev: Overview,  Up: Overview
  69.  
  70. History
  71. =======
  72.  
  73. One spur behind BFD was the desire, on the part of the GNU 960 team at
  74. Intel Oregon, for interoperability of applications on their COFF and
  75. b.out file formats.  Cygnus was providing GNU support for the team,
  76. and Cygnus was contracted to provide the required functionality.
  77.  
  78. The name came from a conversation David Wallace was having with Richard
  79. Stallman about the library: RMS said that it would be quite
  80. hard--David said "BFD".  Stallman was right, but the name stuck.
  81.  
  82. At the same time, Ready Systems wanted much the same thing, but for
  83. different object file formats: IEEE-695, Oasys, Srecords, a.out and
  84. 68k coff.
  85.  
  86. BFD was first implemented by members of Cygnus Support; Steve
  87. Chamberlain (sac@cygnus.com), John Gilmore (gnu@cygnus.com), K. 
  88. Richard Pixley (rich@cygnus.com) and David Henkel-Wallace
  89. (gumby@cygnus.com).
  90.  
  91.  
  92. 
  93. File: bfd.info,  Node: How It Works,  Next: What BFD Version 1 Can Do,  Prev: History,  Up: Overview
  94.  
  95. How It Works
  96. ============
  97.  
  98. To use the library, include `bfd.h' and link with `libbfd.a'.    
  99.  
  100. BFD provides a common interface to the parts of an object file for a
  101. calling application.
  102.  
  103. When an application sucessfully opens a target file (object, archive or
  104. whatever) a pointer to an internal structure is returned. This
  105. pointer points to a structure called `bfd', described in
  106. `include/bfd.h'.  Our convention is to call this pointer a BFD, and
  107. instances of it within code `abfd'.  All operations on the target
  108. object file are applied as methods to the BFD.  The mapping is
  109. defined within `bfd.h' in a set of macros, all beginning `bfd'_.
  110.  
  111. For example, this sequence would do what you would probably expect:
  112. return the number of sections in an object file attached to a BFD
  113. `abfd'.
  114.  
  115. #include "bfd.h"
  116.  
  117. unsigned int number_of_sections(abfd)
  118. bfd *abfd;
  119. {
  120.   return bfd_count_sections(abfd);
  121. }
  122.  
  123. The abstraction used within BFD is that an object file has a header, a
  124. number of sections containing raw data, a set of relocations, and
  125. some symbol information. Also, BFDs opened for archives have the
  126. additional attribute of an index and contain subordinate BFDs. This
  127. approach is fine for a.out and coff, but loses efficiency when
  128. applied to formats such as S-records and IEEE-695.
  129.  
  130.  
  131. 
  132. File: bfd.info,  Node: What BFD Version 1 Can Do,  Prev: How It Works,  Up: Overview
  133.  
  134. What BFD Version 1 Can Do
  135. =========================
  136.  
  137. As different information from the the object files is required, BFD
  138. reads from different sections of the file and processes them.  For
  139. example a very common operation for the linker is processing symbol
  140. tables.  Each BFD back end provides a routine for converting between
  141. the object file's representation of symbols and an internal canonical
  142. format. When the linker asks for the symbol table of an object file,
  143. it calls through the memory pointer to the relevant BFD back end
  144. routine which reads and converts the table into a canonical form. 
  145. The linker then operates upon the canonical form. When the link is
  146. finished and the linker writes the output file's symbol table,
  147. another BFD back end routine is called which takes the newly created
  148. symbol table and converts it into the chosen output format.
  149.  
  150. * Menu:
  151.  
  152. * BFD information loss::    Information Loss
  153. * Mechanism::            Mechanism
  154.  
  155.  
  156. 
  157. File: bfd.info,  Node: BFD information loss,  Next: Mechanism,  Prev: What BFD Version 1 Can Do,  Up: What BFD Version 1 Can Do
  158.  
  159. Information Loss
  160. ----------------
  161.  
  162. *Some information is lost due to the nature of the file format.* The
  163. output targets supported by BFD do not provide identical facilities,
  164. and information which may be described in one form has nowhere to go
  165. in another format. One example of this is alignment information in
  166. `b.out'. There is nowhere in an `a.out' format file to store
  167. alignment information on the contained data, so when a file is linked
  168. from `b.out' and an `a.out' image is produced, alignment information
  169. will not propagate to the output file. (The linker will still use the
  170. alignment information internally, so the link is performed correctly).
  171.  
  172. Another example is COFF section names. COFF files may contain an
  173. unlimited number of sections, each one with a textual section name.
  174. If the target of the link is a format which does not have many
  175. sections (eg `a.out') or has sections without names (eg the Oasys
  176. format) the link cannot be done simply. You can circumvent this
  177. problem by describing the desired input-to-output section mapping
  178. with the linker command language.
  179.  
  180. *Information can be lost during canonicalization.* The BFD internal
  181. canonical form of the external formats is not exhaustive; there are
  182. structures in input formats for which there is no direct
  183. representation internally.  This means that the BFD back ends cannot
  184. maintain all possible data richness through the transformation
  185. between external to internal and back to external formats.
  186.  
  187. This limitation is only a problem when an application reads one format
  188. and writes another.  Each BFD back end is responsible for maintaining
  189. as much data as possible, and the internal BFD canonical form has
  190. structures which are opaque to the BFD core, and exported only to the
  191. back ends. When a file is read in one format, the canonical form is
  192. generated for BFD and the application. At the same time, the back end
  193. saves away any information which may otherwise be lost. If the data
  194. is then written back in the same format, the back end routine will be
  195. able to use the canonical form provided by the BFD core as well as
  196. the information it prepared earlier.  Since there is a great deal of
  197. commonality between back ends, this mechanism is very useful. There
  198. is no information lost for this reason when linking or copying big
  199. endian COFF to little endian COFF, or `a.out' to `b.out'.  When a
  200. mixture of formats is linked, the information is only lost from the
  201. files whose format differs from the destination.
  202.  
  203.  
  204. 
  205. File: bfd.info,  Node: Mechanism,  Prev: BFD information loss,  Up: What BFD Version 1 Can Do
  206.  
  207. Mechanism
  208. ---------
  209.  
  210. The greatest potential for loss of information is when there is least
  211. overlap between the information provided by the source format, that
  212. stored by the canonical format, and the information needed by the
  213. destination format. A brief description of the canonical form may
  214. help you appreciate what kinds of data you can count on preserving
  215. across conversions.
  216.  
  217. *files*
  218. Information on target machine architecture, particular implementation
  219. and format type are stored on a per-file basis. Other information
  220. includes a demand pageable bit and a write protected bit.  Note that
  221. information like Unix magic numbers is not stored here--only the
  222. magic numbers' meaning, so a `ZMAGIC' file would have both the demand
  223. pageable bit and the write protected text bit set.  The byte order of
  224. the target is stored on a per-file basis, so that big- and
  225. little-endian object files may be linked with one another.
  226.  
  227. *sections*
  228. Each section in the input file contains the name of the section, the
  229. original address in the object file, various flags, size and
  230. alignment information and pointers into other BFD data structures.
  231.  
  232. *symbols*
  233. Each symbol contains a pointer to the object file which originally
  234. defined it, its name, its value, and various flag bits.  When a BFD
  235. back end reads in a symbol table, the back end relocates all symbols
  236. to make them relative to the base of the section where they were
  237. defined.  This ensures that each symbol points to its containing
  238. section.  Each symbol also has a varying amount of hidden data to
  239. contain private data for the BFD back end.  Since the symbol points
  240. to the original file, the private data format for that symbol is
  241. accessible.  `gld' can operate on a collection of symbols of wildly
  242. different formats without problems.
  243.  
  244. Normal global and simple local symbols are maintained on output, so
  245. an output file (no matter its format) will retain symbols pointing to
  246. functions and to global, static, and common variables.  Some symbol
  247. information is not worth retaining; in `a.out' type information is
  248. stored in the symbol table as long symbol names.  This information
  249. would be useless to most COFF debuggers; the linker has command line
  250. switches to allow users to throw it away.
  251.  
  252. There is one word of type information within the symbol, so if the
  253. format supports symbol type information within symbols (for example
  254. COFF, IEEE, Oasys) and the type is simple enough to fit within one
  255. word (nearly everything but aggregates) the information will be
  256. preserved.
  257.  
  258. *relocation level*
  259. Each canonical BFD relocation record contains a pointer to the symbol
  260. to relocate to, the offset of the data to relocate, the section the
  261. data is in and a pointer to a relocation type descriptor. Relocation
  262. is performed effectively by message passing through the relocation
  263. type descriptor and symbol pointer. It allows relocations to be
  264. performed on output data using a relocation method only available in
  265. one of the input formats. For instance, Oasys provides a byte
  266. relocation format.  A relocation record requesting this relocation
  267. type would point indirectly to a routine to perform this, so the
  268. relocation may be performed on a byte being written to a COFF file,
  269. even though 68k COFF has no such relocation type.
  270.  
  271. *line numbers*
  272. Object formats can contain, for debugging purposes, some form of
  273. mapping between symbols, source line numbers, and addresses in the
  274. output file.  These addresses have to be relocated along with the
  275. symbol information.  Each symbol with an associated list of line
  276. number records points to the first record of the list.  The head of a
  277. line number list consists of a pointer to the symbol, which allows
  278. divination of the address of the function whose line number is being
  279. described. The rest of the list is made up of pairs: offsets into the
  280. section and line numbers. Any format which can simply derive this
  281. information can pass it successfully between formats (COFF, IEEE and
  282. Oasys).
  283.  
  284.  
  285. 
  286. File: bfd.info,  Node: BFD front end,  Next: BFD back end,  Prev: Overview,  Up: Top
  287.  
  288. BFD front end
  289. *************
  290.  
  291. `typedef bfd'
  292. =============
  293.  
  294. A BFD is has type `bfd'; objects of this type are the cornerstone of
  295. any application using `libbfd'. References though the BFD and to data
  296. in the BFD give the entire BFD functionality.  Here is the struct
  297. used to define the type `bfd'.  This contains he major data about the
  298. file, and contains pointers to the rest of the data.
  299.  
  300. .
  301.  
  302. struct _bfd 
  303. {
  304.         /* The filename the application opened the BFD with.  */
  305.     CONST char *filename;                
  306.  
  307.         /* A pointer to the target jump table.             */
  308.     struct bfd_target *xvec;
  309.  
  310.         /* To avoid dragging too many header files into every file that
  311.        includes `<<bfd.h>>', IOSTREAM has been declared as a "char
  312.        *", and MTIME as a "long".  Their correct types, to which they
  313.        are cast when used, are "FILE *" and "time_t".    The iostream
  314.        is the result of an fopen on the filename. */
  315.     char *iostream;
  316.  
  317.         /* Is the file being cached */
  318.  
  319.     boolean cacheable;
  320.  
  321.         /* Marks whether there was a default target specified when the
  322.        BFD was opened. This is used to select what matching algorithm
  323.        to use to chose the back end. */
  324.  
  325.     boolean target_defaulted;
  326.  
  327.         /* The caching routines use these to maintain a
  328.        least-recently-used list of BFDs */
  329.  
  330.     struct _bfd *lru_prev, *lru_next;
  331.  
  332.         /* When a file is closed by the caching routines, BFD retains
  333.        state information on the file here: 
  334.      */
  335.  
  336.     file_ptr where;              
  337.  
  338.         /* and here:*/
  339.  
  340.     boolean opened_once;
  341.  
  342.         /* Set if we have a locally maintained mtime value, rather than
  343.        getting it from the file each time: */
  344.  
  345.     boolean mtime_set;
  346.  
  347.         /* File modified time, if mtime_set is true: */
  348.  
  349.     long mtime;          
  350.  
  351.         /* Reserved for an unimplemented file locking extension.*/
  352.  
  353.     int ifd;
  354.  
  355.         /* The format which belongs to the BFD.*/
  356.  
  357.     bfd_format format;
  358.  
  359.         /* The direction the BFD was opened with*/
  360.  
  361.     enum bfd_direction {no_direction = 0,
  362.                         read_direction = 1,
  363.                         write_direction = 2,
  364.                         both_direction = 3} direction;
  365.  
  366.         /* Format_specific flags*/
  367.  
  368.     flagword flags;              
  369.  
  370.         /* Currently my_archive is tested before adding origin to
  371.        anything. I believe that this can become always an add of
  372.        origin, with origin set to 0 for non archive files.   */
  373.  
  374.     file_ptr origin;             
  375.  
  376.         /* Remember when output has begun, to stop strange things
  377.        happening. */
  378.     boolean output_has_begun;
  379.  
  380.         /* Pointer to linked list of sections*/
  381.     struct sec  *sections;
  382.  
  383.         /* The number of sections */
  384.     unsigned int section_count;
  385.  
  386.         /* Stuff only useful for object files: 
  387.        The start address. */
  388.     bfd_vma start_address;
  389.  
  390.         /* Used for input and output*/
  391.     unsigned int symcount;
  392.  
  393.         /* Symbol table for output BFD*/
  394.     struct symbol_cache_entry  **outsymbols;             
  395.  
  396.         /* Pointer to structure which contains architecture information*/
  397.     struct bfd_arch_info *arch_info;
  398.  
  399.         /* Stuff only useful for archives:*/
  400.     PTR arelt_data;              
  401.     struct _bfd *my_archive;     
  402.     struct _bfd *next;           
  403.     struct _bfd *archive_head;   
  404.     boolean has_armap;           
  405.  
  406.         /* Used by the back end to hold private data. */
  407.  
  408.     union 
  409.       {
  410.       struct aout_data_struct *aout_data;
  411.       struct artdata *aout_ar_data;
  412.       struct _oasys_data *oasys_obj_data;
  413.       struct _oasys_ar_data *oasys_ar_data;
  414.       struct coff_tdata *coff_obj_data;
  415.       struct ieee_data_struct *ieee_data;
  416.       struct ieee_ar_data_struct *ieee_ar_data;
  417.       struct srec_data_struct *srec_data;
  418.       struct elf_obj_tdata_struct *elf_obj_data;
  419.       struct elf_core_tdata_struct *elf_core_data;
  420.       struct bout_data_struct *bout_data;
  421.       struct sun_core_struct *sun_core_data;
  422.       struct trad_core_struct *trad_core_data;
  423.       PTR any;
  424.       } tdata;
  425.  
  426.         /* Used by the application to hold private data*/
  427.     PTR usrdata;
  428.  
  429.         /* Where all the allocated stuff under this BFD goes */
  430.     struct obstack memory;
  431.  
  432.     asymbol **ld_symbols;
  433. };
  434.  
  435. `bfd_get_reloc_upper_bound'
  436. ...........................
  437.  
  438. *Synopsis*
  439.  
  440. unsigned int bfd_get_reloc_upper_bound(bfd *abfd, asection *sect);
  441.  
  442. *Description*
  443.  This function return the number of bytes required to store the relocation
  444. information associated with section `sect' attached to bfd `abfd'
  445.  
  446. `bfd_canonicalize_reloc'
  447. ........................
  448.  
  449. *Synopsis*
  450.  
  451. unsigned int bfd_canonicalize_reloc
  452.    (bfd *abfd,
  453.     asection *sec,
  454.     arelent **loc,
  455.     asymbol    **syms);
  456.  
  457. *Description*
  458.  This function calls the back end associated with the open `abfd' and
  459. translates the external form of the relocation information attached
  460. to `sec' into the internal canonical form.  The table is placed into
  461. memory at `loc', which has been preallocated, usually by a call to
  462. `bfd_get_reloc_upper_bound'.  The `syms' table is also needed for
  463. horrible internal magic reasons.
  464.  
  465. `bfd_set_file_flags'
  466. ....................
  467.  
  468. *Synopsis*
  469.  
  470. boolean bfd_set_file_flags(bfd *abfd, flagword flags);
  471.  
  472. *Description*
  473.  This function attempts to set the flag word in the referenced BFD
  474. structure to the value supplied.  Possible errors are:
  475.  
  476. * The flag word contained a bit which was not applicable to the type of
  477. file. eg, an attempt was made to set the D_PAGED bit on a bfd format
  478. which does not support demand paging
  479.  
  480.  
  481. `bfd_set_reloc'
  482. ................
  483.  
  484. *Synopsis*
  485.  
  486. void bfd_set_reloc
  487.    (bfd *abfd, asection *sec, arelent **rel, unsigned int count)
  488.  
  489. *Description*
  490.  This function sets the relocation pointer and count within a section to
  491. the supplied values.
  492.  
  493. `bfd_set_start_address'
  494. .......................
  495.  
  496. *Description*
  497.  Marks the entry point of an output BFD.
  498.  
  499. *Returns*
  500.  Returns `true' on success, `false' otherwise.
  501.  
  502. *Synopsis*
  503.  
  504. boolean bfd_set_start_address(bfd *, bfd_vma);
  505.  
  506. `The bfd_get_mtime function'
  507. ............................
  508.  
  509. *Synopsis*
  510.  
  511. long bfd_get_mtime(bfd *);
  512.  
  513. *Description*
  514.  Return file modification time (as read from file system, or from archive
  515. header for archive members).
  516.  
  517. `stuff'
  518. .......
  519.  
  520. *Description*
  521.  stuff which should be documented
  522.  
  523. #define bfd_sizeof_headers(abfd, reloc) \
  524.      BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
  525.  
  526. #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
  527.      BFD_SEND (abfd, _bfd_find_nearest_line,  (abfd, sec, syms, off, file, func, line))
  528.  
  529. #define bfd_debug_info_start(abfd) \
  530.         BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
  531.  
  532. #define bfd_debug_info_end(abfd) \
  533.         BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
  534.  
  535. #define bfd_debug_info_accumulate(abfd, section) \
  536.         BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
  537.  
  538. #define bfd_stat_arch_elt(abfd, stat) \
  539.         BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
  540.  
  541. #define bfd_coff_swap_aux_in(a,e,t,c,i) \
  542.         BFD_SEND (a, _bfd_coff_swap_aux_in, (a,e,t,c,i))
  543.  
  544. #define bfd_coff_swap_sym_in(a,e,i) \
  545.         BFD_SEND (a, _bfd_coff_swap_sym_in, (a,e,i))
  546.  
  547. #define bfd_coff_swap_lineno_in(a,e,i) \
  548.         BFD_SEND ( a, _bfd_coff_swap_lineno_in, (a,e,i))
  549.  
  550. #define bfd_set_arch_mach(abfd, arch, mach)\
  551.         BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
  552.  
  553. #define bfd_coff_swap_reloc_out(abfd, i, o) \
  554.         BFD_SEND (abfd, _bfd_coff_swap_reloc_out, (abfd, i, o))
  555.  
  556. #define bfd_coff_swap_lineno_out(abfd, i, o) \
  557.         BFD_SEND (abfd, _bfd_coff_swap_lineno_out, (abfd, i, o))
  558.  
  559. #define bfd_coff_swap_aux_out(abfd, i, t,c,o) \
  560.         BFD_SEND (abfd, _bfd_coff_swap_aux_out, (abfd, i,t,c, o))
  561.  
  562. #define bfd_coff_swap_sym_out(abfd, i,o) \
  563.         BFD_SEND (abfd, _bfd_coff_swap_sym_out, (abfd, i, o))
  564.  
  565. #define bfd_coff_swap_scnhdr_out(abfd, i,o) \
  566.         BFD_SEND (abfd, _bfd_coff_swap_scnhdr_out, (abfd, i, o))
  567.  
  568. #define bfd_coff_swap_filehdr_out(abfd, i,o) \
  569.         BFD_SEND (abfd, _bfd_coff_swap_filehdr_out, (abfd, i, o))
  570.  
  571. #define bfd_coff_swap_aouthdr_out(abfd, i,o) \
  572.         BFD_SEND (abfd, _bfd_coff_swap_aouthdr_out, (abfd, i, o))
  573.  
  574. #define bfd_get_relocated_section_contents(abfd, seclet) \
  575.     BFD_SEND (abfd, _bfd_get_relocated_section_contents, (abfd, seclet))
  576.  
  577. #define bfd_relax_section(abfd, section, symbols) \
  578.        BFD_SEND (abfd, _bfd_relax_section, (abfd, section, symbols))
  579.  
  580.  
  581. * Menu:
  582.  
  583. * Memory Usage::
  584. * Initialization::
  585. * Sections::
  586. * Symbols::
  587. * Archives::
  588. * Formats::
  589. * Relocations::
  590. * Core Files::
  591. * Targets::
  592. * Architectures::
  593. * Opening and Closing::
  594. * Constructors::
  595. * Internal::
  596. * File Caching::
  597.  
  598.  
  599. 
  600. File: bfd.info,  Node: Memory Usage,  Next: Initialization,  Prev: BFD front end,  Up: BFD front end
  601.  
  602. Memory Usage
  603. ============
  604.  
  605. BFD keeps all its internal structures in obstacks. There is one obstack
  606. per open BFD file, into which the current state is stored. When a BFD
  607. is closed, the obstack is deleted, and so everything which has been
  608. allocated by libbfd for the closing file will be thrown away.
  609.  
  610. BFD will not free anything created by an application, but pointers into
  611. `bfd' structures will be invalidated on a `bfd_close'; for example,
  612. after a `bfd_close' the vector passed to `bfd_canonicalize_symtab'
  613. will still be around, since it has been allocated by the application,
  614. but the data that it pointed to will be lost.
  615.  
  616. The general rule is not to close a BFD until all operations dependent
  617. upon data from the BFD have been completed, or all the data from
  618. within the file has been copied. To help with the management of
  619. memory, there is a function (`bfd_alloc_size') which returns the
  620. number of bytes in obstacks associated with the supplied BFD. This
  621. could be used to select the greediest open BFD, close it to reclaim
  622. the memory, perform some operation and reopen the BFD again, to get a
  623. fresh copy of the data structures.
  624.  
  625.  
  626. 
  627. File: bfd.info,  Node: Initialization,  Next: Sections,  Prev: Memory Usage,  Up: BFD front end
  628.  
  629. Initialization
  630. ==============
  631.  
  632. This is the initialization section
  633.  
  634. `bfd_init'
  635. ..........
  636.  
  637. *Synopsis*
  638.  
  639. void bfd_init(void);
  640.  
  641. *Description*
  642.  This routine must be called before any other bfd function to initialize
  643. magical internal data structures.
  644.  
  645. `bfd_check_init'
  646. ................
  647.  
  648. *Description*
  649.  This routine is called before any other bfd function using initialized
  650. data is used to ensure that the structures have been initialized.
  651. Soon this function will go away, and the bfd library will assume that
  652. bfd_init has been called.
  653.  
  654. *Synopsis*
  655.  
  656. void bfd_check_init(void);
  657.  
  658.  
  659. 
  660. File: bfd.info,  Node: Sections,  Next: Symbols,  Prev: Initialization,  Up: BFD front end
  661.  
  662. Sections
  663. ========
  664.  
  665. Sections are supported in BFD in `section.c'.  The raw data contained
  666. within a BFD is maintained through the section abstraction.  A single
  667. BFD may have any number of sections, and keeps hold of them by
  668. pointing to the first, each one points to the next in the list.
  669.  
  670. * Menu:
  671.  
  672. * Section Input::
  673. * Section Output::
  674. * typedef asection::
  675. * section prototypes::
  676.  
  677.  
  678.  
  679. 
  680. File: bfd.info,  Node: Section Input,  Next: Section Output,  Prev: Sections,  Up: Sections
  681.  
  682. Section Input
  683. -------------
  684.  
  685. When a BFD is opened for reading, the section structures are created
  686. and attached to the BFD.  Each section has a name which describes the
  687. section in the outside world - for example, `a.out' would contain at
  688. least three sections, called `.text', `.data' and `.bss'.  Sometimes
  689. a BFD will contain more than the 'natural' number of sections. A back
  690. end may attach other sections containing constructor data, or an
  691. application may add a section (using bfd_make_section) to the
  692. sections attached to an already open BFD. For example, the linker
  693. creates a supernumary section `COMMON' for each input file's BFD to
  694. hold information about common storage.  The raw data is not
  695. necessarily read in at the same time as the section descriptor is
  696. created. Some targets may leave the data in place until a
  697. `bfd_get_section_contents' call is made. Other back ends may read in
  698. all the data at once - For example; an S-record file has to be read
  699. once to determine the size of the data. An IEEE-695 file doesn't
  700. contain raw data in sections, but data and relocation expressions
  701. intermixed, so the data area has to be parsed to get out the data and
  702. relocations.
  703.  
  704.  
  705. 
  706. File: bfd.info,  Node: Section Output,  Next: typedef asection,  Prev: Section Input,  Up: Sections
  707.  
  708. Section Output
  709. --------------
  710.  
  711. To write a new object style BFD, the various sections to be written
  712. have to be created. They are attached to the BFD in the same way as
  713. input sections, data is written to the sections using
  714. `bfd_set_section_contents'.   The linker uses the fields
  715. `output_section' and `output_offset' to create an output file.  The
  716. data to be written comes from input sections attached to the output
  717. sections.  The output section structure can be considered a filter
  718. for the input section, the output section determines the vma of the
  719. output data and the name, but the input section determines the offset
  720. into the output section of the data to be written.  Eg to create a
  721. section "O", starting at 0x100, 0x123 long, containing two
  722. subsections, "A" at offset 0x0 (ie at vma 0x100) and "B" at offset
  723. 0x20 (ie at vma 0x120) the structures would look like:
  724.  
  725.    section name          "A"
  726.      output_offset   0x00
  727.      size            0x20
  728.      output_section ----------->  section name    "O"
  729.                              |    vma             0x100
  730.    section name          "B" |    size            0x123
  731.      output_offset   0x20    |
  732.      size            0x103   |
  733.      output_section  --------|
  734.  
  735.  
  736. Seglets
  737. --------
  738.  
  739. The data within a section is stored in a `seglet'.  These are much like
  740. the fixups in `gas'.  The seglet abstraction allows the a section to
  741. grow and shrink within itself.  A seglet knows how big it is, and
  742. which is the next seglet and where the raw data for it is, and also
  743. points to a list of relocations which apply to it.  The seglet is
  744. used by the linker to perform relaxing on final code.  The
  745. application creates code which is as big as necessary to make it work
  746. without relaxing, and the user can select whether to relax. 
  747. Sometimes relaxing takes a lot of time.  The linker runs around the
  748. relocations to see if any are attached to data which can be shrunk,
  749. if so it does it on a seglet by seglet basis.
  750.  
  751.  
  752. 
  753. File: bfd.info,  Node: typedef asection,  Next: section prototypes,  Prev: Section Output,  Up: Sections
  754.  
  755. typedef asection
  756. ----------------
  757.  
  758. The shape of a section struct:
  759.  
  760. .
  761.  
  762. typedef struct sec 
  763. {
  764.             /* The name of the section, the name isn't a copy, the pointer is
  765.         the same as that passed to bfd_make_section. */
  766.  
  767.     CONST char *name;
  768.  
  769.  
  770.             /* Which section is it 0.nth      */
  771.  
  772.    int index;                      
  773.  
  774.             /* The next section in the list belonging to the BFD, or NULL. */
  775.  
  776.     struct sec *next;
  777.  
  778.             /* The field flags contains attributes of the section. Some of
  779.            flags are read in from the object file, and some are
  780.            synthesized from other information.  */         
  781.  
  782.     flagword flags;
  783.  
  784. #define SEC_NO_FLAGS   0x000
  785.  
  786.             /* Tells the OS to allocate space for this section when loaded.
  787.            This would clear for a section containing debug information
  788.            only. */
  789.  
  790.  
  791. #define SEC_ALLOC      0x001
  792.             /* Tells the OS to load the section from the file when loading.
  793.            This would be clear for a .bss section */
  794.  
  795. #define SEC_LOAD       0x002
  796.             /* The section contains data still to be relocated, so there will
  797.            be some relocation information too. */
  798.  
  799. #define SEC_RELOC      0x004
  800.  
  801.             /* Obsolete ? */
  802.  
  803. #define SEC_BALIGN     0x008
  804.  
  805.             /* A signal to the OS that the section contains read only
  806.           data. */
  807. #define SEC_READONLY   0x010
  808.  
  809.             /* The section contains code only. */
  810.  
  811. #define SEC_CODE       0x020
  812.  
  813.             /* The section contains data only. */
  814.  
  815. #define SEC_DATA        0x040
  816.  
  817.             /* The section will reside in ROM. */
  818.  
  819. #define SEC_ROM        0x080
  820.  
  821.             /* The section contains constructor information. This section
  822.            type is used by the linker to create lists of constructors and
  823.            destructors used by <<g++>>. When a back end sees a symbol
  824.            which should be used in a constructor list, it creates a new
  825.            section for the type of name (eg <<__CTOR_LIST__>>), attaches
  826.            the symbol to it and builds a relocation. To build the lists
  827.            of constructors, all the linker has to to is catenate all the
  828.            sections called <<__CTOR_LIST__>> and relocte the data
  829.            contained within - exactly the operations it would peform on
  830.            standard data. */
  831.  
  832. #define SEC_CONSTRUCTOR 0x100
  833.  
  834.             /* The section is a constuctor, and should be placed at the
  835.           end of the . */
  836.  
  837.  
  838. #define SEC_CONSTRUCTOR_TEXT 0x1100
  839.  
  840. #define SEC_CONSTRUCTOR_DATA 0x2100
  841.  
  842. #define SEC_CONSTRUCTOR_BSS  0x3100
  843.  
  844.  
  845.             /* The section has contents - a bss section could be
  846.            <<SEC_ALLOC>> | <<SEC_HAS_CONTENTS>>, a debug section could be
  847.            <<SEC_HAS_CONTENTS>> */
  848.  
  849. #define SEC_HAS_CONTENTS 0x200
  850.  
  851.             /* An instruction to the linker not to output sections
  852.           containing this flag even if they have information which
  853.           would normally be written. */
  854.  
  855. #define SEC_NEVER_LOAD 0x400
  856.  
  857.  
  858.  
  859.    bfd_vma vma;
  860.  
  861.             /* The size of the section in bytes, as it will be output.
  862.            contains a value even if the section has no contents (eg, the
  863.            size of <<.bss>>). This will be filled in after relocation */
  864.  
  865.    bfd_size_type _cooked_size;    
  866.  
  867.             /* The size on disk of the section in bytes originally.  Normally this
  868.         value is the same as the size, but if some relaxing has
  869.         been done, then this value will be bigger.  */
  870.  
  871.    bfd_size_type _raw_size;    
  872.  
  873.             /* If this section is going to be output, then this value is the
  874.            offset into the output section of the first byte in the input
  875.            section. Eg, if this was going to start at the 100th byte in
  876.            the output section, this value would be 100. */
  877.  
  878.    bfd_vma output_offset;
  879.  
  880.             /* The output section through which to map on output. */
  881.  
  882.    struct sec *output_section;
  883.  
  884.             /* The alignment requirement of the section, as an exponent - eg
  885.            3 aligns to 2^3 (or 8) */
  886.  
  887.    unsigned int alignment_power;
  888.  
  889.             /* If an input section, a pointer to a vector of relocation
  890.            records for the data in this section. */
  891.  
  892.    struct reloc_cache_entry *relocation;
  893.  
  894.             /* If an output section, a pointer to a vector of pointers to
  895.            relocation records for the data in this section. */
  896.  
  897.    struct reloc_cache_entry **orelocation;
  898.  
  899.             /* The number of relocation records in one of the above  */
  900.  
  901.    unsigned reloc_count;
  902.  
  903.             /* Information below is back end specific - and not always used
  904.            or updated 
  905.  
  906.            File position of section data    */
  907.  
  908.    file_ptr filepos;      
  909.  
  910.             /* File position of relocation info */
  911.  
  912.    file_ptr rel_filepos;
  913.  
  914.             /* File position of line data       */
  915.  
  916.    file_ptr line_filepos;
  917.  
  918.             /* Pointer to data for applications */
  919.  
  920.    PTR userdata;
  921.  
  922.    struct lang_output_section *otheruserdata;
  923.  
  924.             /* Attached line number information */
  925.  
  926.    alent *lineno;
  927.  
  928.             /* Number of line number records   */
  929.  
  930.    unsigned int lineno_count;
  931.  
  932.             /* When a section is being output, this value changes as more
  933.            linenumbers are written out */
  934.  
  935.    file_ptr moving_line_filepos;
  936.  
  937.             /* what the section number is in the target world  */
  938.  
  939.    int target_index;
  940.  
  941.    PTR used_by_bfd;
  942.  
  943.             /* If this is a constructor section then here is a list of the
  944.            relocations created to relocate items within it. */
  945.  
  946.    struct relent_chain *constructor_chain;
  947.  
  948.             /* The BFD which owns the section. */
  949.  
  950.    bfd *owner;
  951.  
  952.    boolean reloc_done;
  953.          /* A symbol which points at this section only */
  954.    struct symbol_cache_entry *symbol;  
  955.    struct symbol_cache_entry **symbol_ptr_ptr;
  956.    struct bfd_seclet_struct *seclets_head;
  957.    struct bfd_seclet_struct *seclets_tail;
  958. } asection ;
  959.  
  960.  
  961. #define BFD_ABS_SECTION_NAME "*ABS*"
  962. #define BFD_UND_SECTION_NAME "*UND*"
  963. #define BFD_COM_SECTION_NAME "*COM*"
  964.  
  965.         /* the absolute section */
  966.  extern   asection bfd_abs_section;
  967.         /* Pointer to the undefined section */
  968.  extern   asection bfd_und_section;
  969.         /* Pointer to the common section */
  970.  extern asection bfd_com_section;
  971.  
  972.  extern struct symbol_cache_entry *bfd_abs_symbol;
  973.  extern struct symbol_cache_entry *bfd_com_symbol;
  974.  extern struct symbol_cache_entry *bfd_und_symbol;
  975. #define bfd_get_section_size_before_reloc(section) \
  976.      (section->reloc_done ? (abort(),1): (section)->_raw_size)
  977. #define bfd_get_section_size_after_reloc(section) \
  978.      ((section->reloc_done) ? (section)->_cooked_size: (abort(),1))
  979.  
  980.  
  981. 
  982. File: bfd.info,  Node: section prototypes,  Prev: typedef asection,  Up: Sections
  983.  
  984. section prototypes
  985. ------------------
  986.  
  987. These are the functions exported by the section handling part of `libbfd'
  988.  
  989. `bfd_get_section_by_name'
  990. .........................
  991.  
  992. *Synopsis*
  993.  
  994. asection *bfd_get_section_by_name(bfd *abfd, CONST char *name);
  995.  
  996. *Description*
  997.  Runs through the provided ABFD and returns the `asection' who's name
  998. matches that provided, otherwise NULL.  *Note Sections::, for more
  999. information.
  1000.  
  1001. `bfd_make_section_old_way'
  1002. ..........................
  1003.  
  1004. *Synopsis*
  1005.  
  1006. asection *bfd_make_section_old_way(bfd *, CONST char *name);
  1007.  
  1008. *Description*
  1009.  This function creates a new empty section called NAME and attaches it to
  1010. the end of the chain of sections for the BFD supplied. An attempt to
  1011. create a section with a name which is already in use, returns its
  1012. pointer without changing the section chain.  It has the funny name
  1013. since this is the way it used to be before is was rewritten... 
  1014. Possible errors are:
  1015.  
  1016. * If output has already started for this BFD.
  1017.  
  1018. * If obstack alloc fails.
  1019.  
  1020.  
  1021. `bfd_make_section'
  1022. ...................
  1023.  
  1024. *Synopsis*
  1025.  
  1026. asection * bfd_make_section(bfd *, CONST char *name);
  1027.  
  1028. *Description*
  1029.  This function creates a new empty section called NAME and attaches it to
  1030. the end of the chain of sections for the BFD supplied. An attempt to
  1031. create a section with a name which is already in use, returns NULL
  1032. without changing the section chain.  Possible errors are:
  1033.  
  1034. *
  1035.  
  1036. `bfd_set_section_flags'
  1037. .......................
  1038.  
  1039. *Synopsis*
  1040.  
  1041. boolean bfd_set_section_flags(bfd *, asection *, flagword);
  1042.  
  1043. *Description*
  1044.  Attempts to set the attributes of the section named in the BFD supplied
  1045. to the value. Returns true on success, false on error. Possible error
  1046. returns are:
  1047.  
  1048. * The section cannot have one or more of the attributes requested. For
  1049. example, a .bss section in `a.out' may not have the
  1050. `SEC_HAS_CONTENTS' field set.
  1051.  
  1052.  
  1053. `bfd_map_over_sections'
  1054. ........................
  1055.  
  1056. *Synopsis*
  1057.  
  1058. void bfd_map_over_sections(bfd *abfd,
  1059.     void (*func)(bfd *abfd,
  1060.     asection *sect,
  1061.     PTR obj),
  1062.     PTR obj);
  1063.  
  1064. *Description*
  1065.  Calls the provided function FUNC for each section attached to the BFD
  1066. ABFD, passing OBJ as an argument. The function will be called as if by
  1067.  
  1068.     func(abfd, the_section, obj);
  1069.  
  1070. This is the prefered method for iterating over sections, an alternative
  1071. would be to use a loop:
  1072.  
  1073.        section *p;
  1074.        for (p = abfd->sections; p != NULL; p = p->next)
  1075.           func(abfd, p, ...)
  1076.  
  1077.  
  1078. `bfd_set_section_size'
  1079. .......................
  1080.  
  1081. *Synopsis*
  1082.  
  1083. boolean bfd_set_section_size(bfd *, asection *, bfd_size_type val);
  1084.  
  1085. *Description*
  1086.  Sets SECTION to the size VAL. If the operation is ok, then `true' is
  1087. returned, else `false'.  Possible error returns:
  1088.  
  1089. * Writing has started to the BFD, so setting the size is invalid
  1090.  
  1091.  
  1092. `bfd_set_section_contents'
  1093. ...........................
  1094.  
  1095. *Synopsis*
  1096.  
  1097. boolean bfd_set_section_contents
  1098.    (bfd *abfd,        
  1099.     asection *section,
  1100.     PTR data,
  1101.     file_ptr offset,
  1102.     bfd_size_type count);
  1103.  
  1104. *Description*
  1105.  Sets the contents of the section SECTION in BFD ABFD to the data starting
  1106. in memory at DATA. The data is written to the output section starting
  1107. at offset OFFSET for COUNT bytes.  Normally `true' is returned, else
  1108. `false'. Possible error returns are:
  1109.  
  1110. * The output section does not have the `SEC_HAS_CONTENTS' attribute, so
  1111. nothing can be written to it.
  1112.  
  1113. * This routine is front end to the back end function
  1114. `_bfd_set_section_contents'.
  1115.  
  1116.  
  1117. `bfd_get_section_contents'
  1118. ...........................
  1119.  
  1120. *Synopsis*
  1121.  
  1122. boolean bfd_get_section_contents 
  1123.    (bfd *abfd, asection *section, PTR location,
  1124.     file_ptr offset, bfd_size_type count);
  1125.  
  1126. *Description*
  1127.  This function reads data from SECTION in BFD ABFD into memory starting at
  1128. LOCATION. The data is read at an offset of OFFSET from the start of
  1129. the input section, and is read for COUNT bytes.  If the contents of a
  1130. constuctor with the `SEC_CONSTUCTOR' flag set are requested, then the
  1131. LOCATION is filled with zeroes. If no errors occur, `true' is
  1132. returned, else `false'.
  1133.  
  1134.  
  1135. 
  1136. File: bfd.info,  Node: Symbols,  Next: Archives,  Prev: Sections,  Up: BFD front end
  1137.  
  1138. Symbols
  1139. =======
  1140.  
  1141. BFD trys to maintain as much symbol information as it can when it moves
  1142. information from file to file. BFD passes information to applications
  1143. though the `asymbol' structure. When the application requests the
  1144. symbol table, BFD reads the table in the native form and translates
  1145. parts of it into the internal format. To maintain more than the
  1146. infomation passed to applications some targets keep some information
  1147. 'behind the sceans', in a structure only the particular back end
  1148. knows about. For example, the coff back end keeps the original symbol
  1149. table structure as well as the canonical structure when a BFD is read
  1150. in. On output, the coff back end can reconstruct the output symbol
  1151. table so that no information is lost, even information unique to coff
  1152. which BFD doesn't know or understand. If a coff symbol table was
  1153. read, but was written through an a.out back end, all the coff
  1154. specific information would be lost. The symbol table of a BFD is not
  1155. necessarily read in until a canonicalize request is made. Then the
  1156. BFD back end fills in a table provided by the application with
  1157. pointers to the canonical information.  To output symbols, the
  1158. application provides BFD with a table of pointers to pointers to
  1159. `asymbol's. This allows applications like the linker to output a
  1160. symbol as read, since the 'behind the sceens' information will be
  1161. still available.
  1162.  
  1163. * Menu:
  1164.  
  1165. * Reading Symbols::
  1166. * Writing Symbols::
  1167. * typedef asymbol::
  1168. * symbol handling functions::
  1169.  
  1170.  
  1171.  
  1172. 
  1173. File: bfd.info,  Node: Reading Symbols,  Next: Writing Symbols,  Prev: Symbols,  Up: Symbols
  1174.  
  1175. Reading Symbols
  1176. ---------------
  1177.  
  1178. There are two stages to reading a symbol table from a BFD; allocating
  1179. storage, and the actual reading process. This is an excerpt from an
  1180. appliction which reads the symbol table:
  1181.  
  1182.       unsigned int storage_needed;
  1183.       asymbol **symbol_table;
  1184.       unsigned int number_of_symbols;
  1185.       unsigned int i;
  1186.  
  1187.       storage_needed = get_symtab_upper_bound (abfd);
  1188.  
  1189.       if (storage_needed == 0) {
  1190.          return ;
  1191.       }
  1192.       symbol_table = (asymbol **) bfd_xmalloc (storage_needed);
  1193.         ...
  1194.       number_of_symbols = 
  1195.          bfd_canonicalize_symtab (abfd, symbol_table); 
  1196.  
  1197.       for (i = 0; i < number_of_symbols; i++) {
  1198.          process_symbol (symbol_table[i]);
  1199.       }
  1200.  
  1201. All storage for the symbols themselves is in an obstack connected to
  1202. the BFD, and is freed when the BFD is closed.
  1203.  
  1204.  
  1205. 
  1206. File: bfd.info,  Node: Writing Symbols,  Next: typedef asymbol,  Prev: Reading Symbols,  Up: Symbols
  1207.  
  1208. Writing Symbols
  1209. ---------------
  1210.  
  1211. Writing of a symbol table is automatic when a BFD open for writing is
  1212. closed. The application attaches a vector of pointers to pointers to
  1213. symbols to the BFD being written, and fills in the symbol count. The
  1214. close and cleanup code reads through the table provided and performs
  1215. all the necessary operations. The outputing code must always be
  1216. provided with an 'owned' symbol; one which has come from another BFD,
  1217. or one which has been created using `bfd_make_empty_symbol'.   An
  1218. example showing the creation of a symbol table with only one element:
  1219.  
  1220.     #include "bfd.h"
  1221.     main() 
  1222.     {
  1223.       bfd *abfd;
  1224.       asymbol *ptrs[2];
  1225.       asymbol *new;
  1226.  
  1227.       abfd = bfd_openw("foo","a.out-sunos-big");
  1228.       bfd_set_format(abfd, bfd_object);
  1229.       new = bfd_make_empty_symbol(abfd);
  1230.       new->name = "dummy_symbol";
  1231.       new->section = bfd_make_section_old_way(abfd, ".text");
  1232.       new->flags = BSF_GLOBAL;
  1233.       new->value = 0x12345;
  1234.  
  1235.       ptrs[0] = new;
  1236.       ptrs[1] = (asymbol *)0;
  1237.  
  1238.       bfd_set_symtab(abfd, ptrs, 1);
  1239.       bfd_close(abfd);
  1240.     }
  1241.  
  1242.     ./makesym 
  1243.     nm foo
  1244.     00012345 A dummy_symbol
  1245.  
  1246. Many formats cannot represent arbitary symbol information; for instance
  1247. the `a.out' object format does not allow an arbitary number of
  1248. sections. A symbol pointing to a section which is not one  of
  1249. `.text', `.data' or `.bss' cannot be described.
  1250.  
  1251.  
  1252. 
  1253. File: bfd.info,  Node: typedef asymbol,  Next: symbol handling functions,  Prev: Writing Symbols,  Up: Symbols
  1254.  
  1255. typedef asymbol
  1256. ---------------
  1257.  
  1258. An `asymbol' has the form:
  1259.  
  1260. .typedef struct symbol_cache_entry
  1261.  
  1262. {
  1263.         /* A pointer to the BFD which owns the symbol. This information
  1264.        is necessary so that a back end can work out what additional
  1265.           (invisible to the application writer) information is carried
  1266.        with the symbol.  */
  1267.  
  1268.   struct _bfd *the_bfd;
  1269.  
  1270.         /* The text of the symbol. The name is left alone, and not copied - the
  1271.        application may not alter it. */
  1272.   CONST char *name;
  1273.  
  1274.         /* The value of the symbol.*/
  1275.   symvalue value;
  1276.  
  1277.         /* Attributes of a symbol: */
  1278.  
  1279. #define BSF_NO_FLAGS    0x00
  1280.  
  1281.         /* The symbol has local scope; <<static>> in <<C>>. The value
  1282.         is the offset into the section of the data. */
  1283. #define BSF_LOCAL    0x01
  1284.  
  1285.         /* The symbol has global scope; initialized data in <<C>>. The
  1286.        value is the offset into the section of the data. */
  1287. #define BSF_GLOBAL    0x02
  1288.  
  1289.         /* Obsolete */
  1290. #define BSF_IMPORT    0x04
  1291.  
  1292.         /* The symbol has global scope, and is exported. The value is
  1293.        the offset into the section of the data. */
  1294. #define BSF_EXPORT    0x08
  1295.  
  1296.         /* The symbol is undefined. <<extern>> in <<C>>. The value has
  1297.        no meaning. */
  1298. #define BSF_UNDEFINED_OBS 0x10    
  1299.  
  1300.         /* The symbol is common, initialized to zero; default in
  1301.        <<C>>. The value is the size of the object in bytes. */
  1302. #define BSF_FORT_COMM_OBS    0x20    
  1303.  
  1304.         /* A normal C symbol would be one of:
  1305.        <<BSF_LOCAL>>, <<BSF_FORT_COMM>>,  <<BSF_UNDEFINED>> or
  1306.        <<BSF_EXPORT|BSD_GLOBAL>> */
  1307.  
  1308.         /* The symbol is a debugging record. The value has an arbitary
  1309.        meaning. */
  1310. #define BSF_DEBUGGING    0x40
  1311.  
  1312.         /* Used by the linker */
  1313. #define BSF_KEEP        0x10000
  1314. #define BSF_KEEP_G      0x80000
  1315.  
  1316.         /* Unused */
  1317. #define BSF_WEAK        0x100000
  1318. #define BSF_CTOR        0x200000 
  1319.  
  1320.            /* This symbol was created to point to a section */
  1321. #define BSF_SECTION_SYM 0x400000 
  1322.  
  1323.         /* The symbol used to be a common symbol, but now it is
  1324.        allocated. */
  1325. #define BSF_OLD_COMMON  0x800000  
  1326.  
  1327.         /* The default value for common data. */
  1328. #define BFD_FORT_COMM_DEFAULT_VALUE 0
  1329.  
  1330.         /* In some files the type of a symbol sometimes alters its
  1331.        location in an output file - ie in coff a <<ISFCN>> symbol
  1332.        which is also <<C_EXT>> symbol appears where it was
  1333.        declared and not at the end of a section.  This bit is set
  1334.          by the target BFD part to convey this information. */
  1335.  
  1336. #define BSF_NOT_AT_END    0x40000
  1337.  
  1338.         /* Signal that the symbol is the label of constructor section. */
  1339. #define BSF_CONSTRUCTOR   0x1000000
  1340.  
  1341.         /* Signal that the symbol is a warning symbol. If the symbol
  1342.        is a warning symbol, then the value field (I know this is
  1343.        tacky) will point to the asymbol which when referenced will
  1344.        cause the warning. */
  1345. #define BSF_WARNING       0x2000000
  1346.  
  1347.         /* Signal that the symbol is indirect. The value of the symbol
  1348.        is a pointer to an undefined asymbol which contains the
  1349.        name to use instead. */
  1350. #define BSF_INDIRECT     0x4000000
  1351.  
  1352.   flagword flags;
  1353.  
  1354.         /* A pointer to the section to which this symbol is 
  1355.        relative.  This will always be non NULL, there are special
  1356.           sections for undefined and absolute symbols */
  1357.   struct sec *section;
  1358.  
  1359.         /* Back end special data. This is being phased out in favour
  1360.        of making this a union. */
  1361.   PTR udata;    
  1362.  
  1363. } asymbol;
  1364.  
  1365.  
  1366. 
  1367. File: bfd.info,  Node: symbol handling functions,  Prev: typedef asymbol,  Up: Symbols
  1368.  
  1369. Symbol Handling Functions
  1370. -------------------------
  1371.  
  1372.  
  1373. `get_symtab_upper_bound'
  1374. .........................
  1375.  
  1376. *Description*
  1377.  Returns the number of bytes required in a vector of pointers to
  1378. `asymbols' for all the symbols in the supplied BFD, including a
  1379. terminal NULL pointer. If there are no symbols in the BFD, then 0 is
  1380. returned.
  1381.  
  1382. #define get_symtab_upper_bound(abfd) \
  1383.      BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))
  1384.  
  1385.  
  1386. `bfd_canonicalize_symtab'
  1387. ..........................
  1388.  
  1389. *Description*
  1390.  Supplied a BFD and a pointer to an uninitialized vector of pointers. This
  1391. reads in the symbols from the BFD, and fills in the table with
  1392. pointers to the symbols, and a trailing NULL.  The routine returns
  1393. the actual number of symbol pointers not including the NULL.
  1394.  
  1395. #define bfd_canonicalize_symtab(abfd, location) \
  1396.      BFD_SEND (abfd, _bfd_canonicalize_symtab,\
  1397.                   (abfd, location))
  1398.  
  1399.  
  1400. `bfd_set_symtab'
  1401. .................
  1402.  
  1403. *Description*
  1404.  Provided a table of pointers to symbols and a count, writes to the output
  1405. BFD the symbols when closed.
  1406.  
  1407. *Synopsis*
  1408.  
  1409. boolean bfd_set_symtab (bfd *, asymbol **, unsigned int );
  1410.  
  1411. `bfd_print_symbol_vandf'
  1412. ........................
  1413.  
  1414. *Description*
  1415.  Prints the value and flags of the symbol supplied to the stream file.
  1416.  
  1417. *Synopsis*
  1418.  
  1419. void bfd_print_symbol_vandf(PTR file, asymbol *symbol);
  1420.  
  1421. `bfd_make_empty_symbol'
  1422. .......................
  1423.  
  1424. *Description*
  1425.  This function creates a new `asymbol' structure for the BFD, and returns
  1426. a pointer to it.  This routine is necessary, since each back end has
  1427. private information surrounding the `asymbol'. Building your own
  1428. `asymbol' and pointing to it will not create the private information,
  1429. and will cause problems later on.
  1430.  
  1431. #define bfd_make_empty_symbol(abfd) \
  1432.      BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
  1433.  
  1434.  
  1435. `bfd_decode_symclass'
  1436. ......................
  1437.  
  1438. *Description*
  1439.  Return a lower-case character corresponding to the symbol class of symbol.
  1440.  
  1441. *Synopsis*
  1442.  
  1443. int bfd_decode_symclass(asymbol *symbol);
  1444.  
  1445.  
  1446. 
  1447. File: bfd.info,  Node: Archives,  Next: Formats,  Prev: Symbols,  Up: BFD front end
  1448.  
  1449. Archives
  1450. ========
  1451.  
  1452.  
  1453. *Description*
  1454.  Archives are supported in BFD in `archive.c'.  An archive (or library) is
  1455. just another BFD.  It has a symbol table, although there's not much a
  1456. user program will do with it.  The big difference between an archive
  1457. BFD and an ordinary BFD is that the archive doesn't have sections. 
  1458. Instead it has a chain of BFDs considered its contents.  These BFDs
  1459. can be manipulated just like any other.  The BFDs contained in an
  1460. archive opened for reading will all be opened for reading; you may
  1461. put either input or output BFDs into an archive opened for output; it
  1462. will be handled correctly when the archive is closed.  Use
  1463. `bfd_openr_next_archived_file' to step through all the contents of an
  1464. archive opened for input.  It's not required that you read the entire
  1465. archive if you don't want to!  Read it until you find what you want. 
  1466. Archive contents of output BFDs are chained through the `next'
  1467. pointer in a BFD.  The first one is findable through the
  1468. `archive_head' slot of the archive.  Set it with `set_archive_head'
  1469. (q.v.).  A given BFD may be in only one open output archive at a time.
  1470. As expected, the BFD archive code is more general than the archive
  1471. code of any given environment.  BFD archives may contain files of
  1472. different formats (eg a.out and coff) and even different
  1473. architectures.  You may even place archives recursively into archives!
  1474. This can cause unexpected confusion, since some archive formats are
  1475. more expressive than others.  For instance intel COFF archives can
  1476. preserve long filenames; Sun a.out archives cannot.  If you move a
  1477. file from the first to the second format and back again, the filename
  1478. may be truncated.  Likewise, different a.out environments have
  1479. different conventions as to how they truncate filenames, whether they
  1480. preserve directory names in filenames, etc.  When interoperating with
  1481. native tools, be sure your files are homogeneous.  Beware: most of
  1482. these formats do not react well to the presence of spaces in
  1483. filenames.  We do the best we can, but can't always handle this due
  1484. to restrctions in the format of archives.  Many unix utilities are
  1485. braindead in regards to spaces and such in filenames anyway, so this
  1486. shouldn't be much of a restriction.
  1487.  
  1488. `bfd_get_next_mapent'
  1489. .....................
  1490.  
  1491. *Synopsis*
  1492.  
  1493. symindex bfd_get_next_mapent(bfd *, symindex previous, carsym ** sym);
  1494.  
  1495. *Description*
  1496.  This function steps through an archive's symbol table (if it has one). 
  1497. Successively updates `sym' with the next symbol's information,
  1498. returning that symbol's (internal) index into the symbol table. 
  1499. Supply BFD_NO_MORE_SYMBOLS as the `previous' entry to get the first
  1500. one; returns BFD_NO_MORE_SYMBOLS when you're already got the last one.
  1501. A `carsym' is a canonical archive symbol.  The only user-visible
  1502. element is its name, a null-terminated string.
  1503.  
  1504. `bfd_set_archive_head'
  1505. ......................
  1506.  
  1507. *Synopsis*
  1508.  
  1509. boolean bfd_set_archive_head(bfd *output, bfd *new_head);
  1510.  
  1511. *Description*
  1512.  Used whilst processing archives. Sets the head of the chain of BFDs
  1513. contained in an archive to NEW_HEAD.
  1514.  
  1515. `bfd_get_elt_at_index'
  1516. ......................
  1517.  
  1518. *Synopsis*
  1519.  
  1520. bfd *bfd_get_elt_at_index(bfd * archive, int index);
  1521.  
  1522. *Description*
  1523.  Return the bfd which is referenced by the symbol indexed by `index'. 
  1524. `index' should have been returned by `bfd_get_next_mapent' (q.v.).
  1525.  
  1526. `bfd_openr_next_archived_file'
  1527. ..............................
  1528.  
  1529. *Synopsis*
  1530.  
  1531. bfd* bfd_openr_next_archived_file(bfd *archive, bfd *previous);
  1532.  
  1533. *Description*
  1534.  Initially provided a BFD containing an archive and NULL, opens an inpout
  1535. BFD on the first contained element and returns that.  Subsequent
  1536. calls to bfd_openr_next_archived_file should pass the archive and the
  1537. previous return value to return a created BFD to the next contained
  1538. element. NULL is returned when there are no more.
  1539.  
  1540.  
  1541.